home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 November: Tool Chest / Dev.CD Nov 00 TC Disk 1.toast / Sample Code / Networking / MoreNetworkSetup / NetworkSetup / MoreNetworkSetup.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-09-28  |  8.5 KB  |  204 lines  |  [TEXT/CWIE]
  1. /*
  2.     File:        MoreNetworkSetup.h
  3.  
  4.     Contains:    Simple wrappers to make Network Setup easier
  5.  
  6.     Written by:    Quinn
  7.  
  8.     Copyright:    Copyright © 1998 by Apple Computer, Inc., all rights reserved.
  9.  
  10.                 You may incorporate this Apple sample source code into your program(s) without
  11.                 restriction. This Apple sample source code has been provided "AS IS" and the
  12.                 responsibility for its operation is yours. You are not permitted to redistribute
  13.                 this Apple sample source code as "Apple sample source code" after having made
  14.                 changes. If you're going to re-distribute the source, we require that you make
  15.                 it clear in the source that the code was descended from Apple sample source
  16.                 code, but that you've made changes.
  17.  
  18.     Change History (most recent first):
  19.  
  20.          <5>    19/10/99    Quinn   Fix embarrassing spelling error.
  21.          <4>     21/4/99    Quinn   Added MNSGetPrefHandle, MNSSetPrefHandle and MNSIterateEntity.
  22.          <3>    10/11/98    Quinn   Convert "MorePrefix.h" to "MoreSetup.h".
  23.          <2>     5/11/98    Quinn   Fix header.
  24.          <1>     5/11/98    Quinn   First checked in.
  25. */
  26.  
  27. #pragma once
  28.  
  29. /////////////////////////////////////////////////////////////////
  30. // MoreIsBetter Setup
  31.  
  32. #include "MoreSetup.h"
  33.  
  34. /////////////////////////////////////////////////////////////////
  35. // Mac OS Interfaces
  36.  
  37. #include <MacTypes.h>
  38. #include <NetworkSetup.h>
  39.  
  40. /////////////////////////////////////////////////////////////////
  41.  
  42. struct MNSDatabaseRef {
  43.     CfgDatabaseRef dbRef;
  44.     CfgAreaID area;
  45.     CfgAreaID originalArea;
  46. };
  47. typedef struct MNSDatabaseRef MNSDatabaseRef;
  48. typedef MNSDatabaseRef *MNSDatabaseRefPtr;
  49.  
  50. #ifdef __cplusplus
  51. extern "C" {
  52. #endif
  53.  
  54. extern pascal Boolean IsNetworkSetupAvailable(void);
  55.     // This routine tests whether the Network Setup API is available.
  56.     // It may be called by both classic and CFM code.  If called by
  57.     // CFM code, it uses a weak link to see if the library is present,
  58.     // See DTS Technote 1083 "Weak-Linking to a Code Fragment Manager-based
  59.     // Shared Library" for details.
  60.     //
  61.     // <http://developer.apple.com/technotes/tn/tn1083.html>
  62.     //
  63.     // If called by classic 68K code, it uses explicit CFM calls to determine
  64.     // whether the library is present.
  65.     //
  66.     // If Network Setup is not available, calling any of these routines
  67.     // will cause you to crash.  Also, if building classic 68K, calling any
  68.     // other routine in this library will cause a link error because there's
  69.     // no Mixed Mode glue for the Network Setup library.
  70.  
  71. extern pascal Boolean  MNSValidDatabase(const MNSDatabaseRef *ref);
  72.     // Returns true if the database reference passed in is reasonably
  73.     // valid.
  74.     
  75. extern pascal Boolean  MNSDatabaseWritable(const MNSDatabaseRef *ref);
  76.     // Returns true if referenced database is writable.
  77.  
  78. extern pascal OSStatus MNSOpenDatabase(MNSDatabaseRef *ref, Boolean forWriting);
  79.     // Opens the Network Setup database, filling out MNSDatabaseRef to
  80.     // contain the information needed to access it.  This also opens
  81.     // the current area, either for reading or writing depending on
  82.     // the forWriting parameter.
  83.     
  84. extern pascal OSStatus MNSCloseDatabase(MNSDatabaseRef *ref, Boolean commit);
  85.     // Closes the Network Setup database specified by MNSDatabaseRef.
  86.     // If commit is true, it will attempt to commit any changes made
  87.     // to the database.  The database must have been opened for writing.
  88.     // If commit is false, it will throw away changes (if any) made to the
  89.     // database.
  90.  
  91. extern pascal OSStatus MNSGetFixedSizePref(const MNSDatabaseRef *ref,
  92.                         const CfgEntityRef *entityID,
  93.                         OSType prefType,
  94.                         void *buffer, ByteCount prefSize);
  95.     // This routine gets a fixed size preference out of
  96.     // the configuration database described by ref.  entityID
  97.     // is the entity containing the preference.  prefType is the
  98.     // type of preference within the entity.  buffer is the address
  99.     // where the preference data should be put.  prefSize is the size
  100.     // of the buffer, and the routine validates that the preference
  101.     // is exactly that size.
  102.  
  103. extern pascal OSStatus MNSGetPref(const MNSDatabaseRef *ref,
  104.                         const CfgEntityRef *entityID,
  105.                         OSType prefType,
  106.                         void **buffer, ByteCount *prefSize);
  107.     // This routine gets a variable size preference out of
  108.     // the configuration database described by ref.  entityID
  109.     // is the entity containing the preference.  prefType is the
  110.     // type of preference within the entity.  buffer is the address
  111.     // a pointer where the address of the newly allocated preference
  112.     // buffer should be put.  prefSize is the address of a variable
  113.     // where the size of the newly allocated preference should be.
  114.     // 
  115.     // The caller is responsible for disposing of the preference buffer
  116.     // using DisposePtr.  If the routine fails, no preference buffer is 
  117.     // returned.
  118.  
  119. extern pascal OSStatus MNSSetPref(const MNSDatabaseRef *ref,
  120.                         const CfgEntityRef *entityID,
  121.                         OSType prefType,
  122.                         const void *prefData, ByteCount prefSize);
  123.     // This routine sets a preference in the database specified by ref.
  124.     // entityID is the entity containing the preference.  prefType is the
  125.     // type of preference within the entity.  buffer is the address
  126.     // of the new preference data.  prefSize is the size of the new
  127.     // preference data.
  128.  
  129. extern pascal OSStatus MNSGetPrefHandle(const MNSDatabaseRef *ref,
  130.                         const CfgEntityRef *entityID,
  131.                         OSType prefType,
  132.                         Handle prefData);
  133.     // Exactly like MNSGetPref except that it puts the data into
  134.     // prefData, resizing it to fit of course.
  135.     
  136. extern pascal OSStatus MNSSetPrefHandle(const MNSDatabaseRef *ref,
  137.                         const CfgEntityRef *entityID,
  138.                         OSType prefType,
  139.                         Handle prefData);
  140.     // Exactly like MNSSetPref except the data is taken as a handle
  141.     // rather than a pointer and length.
  142.  
  143. typedef pascal void (*MNSPrefIterator)(OSType prefType, void *prefData, ByteCount prefSize, void *refcon);
  144.     // A callback for MNSIterateEntity.  prefType is the type of
  145.     // this preference, prefData points to the preference data,
  146.     // and prefSize is the size of that data.  refcon is exactly
  147.     // the value passed to the refcon parameter of MNSIterateEntity.
  148.  
  149. extern pascal OSStatus MNSIterateEntity(const MNSDatabaseRef *ref,
  150.                                     const CfgEntityRef *entity,
  151.                                     MNSPrefIterator iteratorProc,
  152.                                     void *refcon);
  153.     // This routine iterates through all the preferences stored in 
  154.     // entity, calling iteratorProc on each one.  refcon is passed
  155.     // to iteratorProc without being interpreted by the routine.
  156.  
  157. extern pascal OSStatus MNSGetEntitiesList(const MNSDatabaseRef *ref,
  158.                                 OSType entityClass, OSType entityType,
  159.                                 ItemCount *entityCount,
  160.                                 CfgEntityRef **entityIDs,
  161.                                 CfgEntityInfo **entityInfos);
  162.     // This routine gets a list of all the entities that match
  163.     // class and type in the specified area of the specified database.
  164.     // It allocates buffer- (using NewPtr) to hold the CfgEntityRef's
  165.     // and CfgEntityInfo's and sets *entityIDs and *entityInfos to
  166.     // the buffers.  Pass nil if you don't want to get that particular
  167.     // information.  It sets entityCount to the number of entities found.
  168.  
  169. extern pascal OSStatus MNSFindActiveSet(const MNSDatabaseRef *ref, CfgEntityRef *activeSet);
  170.     // This routine finds the entity ref of the active set entity
  171.     // in the database.  It works by finding all the set entities
  172.     // (there is generally only one in the current OT implementation)
  173.     // and checks each one for the active bit set in its flags.
  174.     // It returns the first set that claims to be active.
  175.  
  176. typedef pascal void (*MNSSetIterator)(const MNSDatabaseRef *ref, CfgSetsElement *thisElement, void *refcon);
  177.     // A callback for MNSIterateSet.  ref and refcon are as
  178.     // specified in the call to MNSIterateSet.  thisElement is
  179.     // a specified set element in the set.  It has fields
  180.     // fEntityRef (the entity ref) and fEntityInfo (the entity info).
  181.     // Your callback can modify these fields and the changes will
  182.     // take effect if writeAfterIterate is specified in the call
  183.     // to MNSIterateSet.
  184.  
  185. extern pascal OSStatus MNSIterateSet(const MNSDatabaseRef *ref,
  186.                                     const CfgEntityRef *setEntity,
  187.                                     MNSSetIterator iteratorProc,
  188.                                     void *refcon,
  189.                                     Boolean writeAfterIterate);
  190.     // This routine iterates through all the entities in the specified
  191.     // set in the database specified by ref.  Pass a set entity
  192.     // in the setEntity parameter.  Pass a pointer to your callback
  193.     // routine in iteratorProc.  refcon is ignored by the routine and
  194.     // simply passed to the iterator.  If writeAfterIterate is true,
  195.     // the set preference is written back to the database after
  196.     // all entities have been enumerated.
  197.     //
  198.     // Typically one would iterate through the active set, found using
  199.     // MNSFindActiveSet.
  200.     
  201. #ifdef __cplusplus
  202. }
  203. #endif
  204.